03 March 2025

Configure Microsoft Entra External ID

BETA Only applicable to institutions using the BETA release. Note that BETA documentation may be incomplete or contain errors.

Configure Entra External ID to create an app registration, define the external authentication URL for Ontrack, grant admin consent, create a user flow, and optionally add your institution's branding to the sign-in page.
Before configuring Entra External ID, you must ensure that you have administrative access to an Entra External Tenant. For more information, go to Create an external tenant.

Configure Entra External ID as follows:

After configuring Entra External ID, you must also configure ebs for Microsoft Entra External ID.

Configure app registration

Entra External ID app registrations can be defined to cover one Ontrack web app, or all Ontrack web apps for a single environment. For example, you can use multiple user flows to enable different authentication options for applicants and staff members. Note that if you want to use multiple flows, you should create a new app registration for each Ontrack website. For more information on app registrations, go to Register an app in your external tenant.

For security reasons using a single app registration for multiple environments, such as live and test, is not recommended.

Create an app registration as follows:

  1. Create an app registration on your Entra external tenant with a meaningful application name. For example, Ontrack Hub.

  2. Go to Supported account types and then select Accounts in this organizational directory only.

  3. Add your ebs Ontrack Web App URL, go to the Redirect URI list, platform Web, and then select Register. Note that the application’s Overview pane is displayed when registration is complete.

  4. Note the Application (client) ID for use in Authentication Institution Settings.

  5. Go to the Authentication pane and enable ID tokens to be issued by the authorisation endpoint, then select Save.

    As part of the registration process you can only add a single URI, but further redirect URIs can be added in the Authentication pane. Tribal recommends adding https://jwt.io to enable decoding of the ID token produced by a test run of the User Flow. This is useful for confirming claim details retuned to ebs after successful authentication of an existing ebs user.

  6. Add optional claims, go to the Token Configuration > Optional claims, and then select the ID token type. Select the optional claims that will be passed through to ebs and then select Add. Note that You may be prompted to enable the Microsoft Graph profile permission, depending upon the claims chosen. If so, choose to Add these.

    We recommend keeping the attributes to a minimum. Only preferred_username is required for signup. If chosen, given_name and family_name will be passed into ebs forename and surname fields.

  7. Create the external authentication Ontrack URL. On the Overview pane, select the Endpoints link to create the external authentication ontrack URL.

Create external authentication Ontrack URL

You must create an external authentication Ontrack URL to use in the ebs institution settings for authentication. The URL is created by taking the OpenID Connect metadata document URL and removing any characters after /v2.0/ as shown in the following example:

  • Original URL: https://TribalebsExternalTest.ciamlogin.com/56ab0cad-fa50-49bc-8612-51e7a95899d6/v2.0/.well-known/openid-configuration

  • Modified URL: https://TribalebsExternalTest.ciamlogin.com/56ab0cad-fa50-49bc-8612-51e7a95899d6/v2.0/

Note the URL for use in the second part of configuring the integration, that is configure ebs for Microsoft Entra External ID.

Grant admin consent

Grant admin consent as follows:

  1. Go to the API Permissions pane.

  2. Select Grant admin consent for <your tenant name> and then select Yes.

  3. Select Refresh and confirm that the Status for the User.Read permission says Granted.

Create a user flow

For more information on user flows in Entra External ID, go to Create self-service sign-up user flows for apps in external tenants.

Create a user flow as follows:

  1. Go to to External Identities > User flows.

  2. Create a new user flow with a unique name. For example, SignInAndSignUp.

  3. Select at least one identity provider, such as Email accounts – Email with password.

  4. Select the required User attributes to be collected from a new user, referring to the Configure app registration section where Claims were defined, and then select Create.

    Tribal recommends keeping the attributes selected to a minimum. Only Email address is required for signup. If chosen, Given name and Surname will be passed into the ebs Forename and Surname fields. Note that Display name is useful for uniquely identifying users in Entra but is not passed to ebs.

  5. Once created, you can select the created user flow to make further configuration changes. For example, on the Page layouts section, you can change the ordering of the fields, labels, and whether a field is required to be entered by the user.

  6. Select Applications and then Add application to link the user flow to the previously created application.

If using Email and password option, it is suggested to enable password reset so that customers can change or reset their password without administrator or help desk involvement. For more information, go to Enable self-service password reset.

Branding (optional)

The Entra External ID tenant is shipped with a default neutral brand. Many aspects of the sign in experience can be configured, including background images, logos, text, and so on. For more information on branding, go to Customize the neutral branding in your external tenant.